IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat5 / acpp.z / acpp

Wrap

Text File | 1998-10-30 | 21.6 KB | 461 lines

AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) NNNNAAAAMMMMEEEE acpp - the ANSI C language preprocessor DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN The ANSI C language preprocessor, _a_c_p_p, is invoked as the first pass of any ANSI C compilation when the _c_c(1) command is issued with the ----aaaaccccpppppppp or ----oooollllddddccccpppppppp option. Thus, _a_c_p_p'_s output is designed to be in a form acceptable as input to the next pass of the C compiler. The use of the _a_c_p_p command is not recommended, since the functionality of _a_c_p_p has been moved into the C front-end and _a_c_p_p may not be supported in future releases. See _m_4(1) for a general macro processor. This preprocessor is a version of GNU cpp. To see which version, use _a_c_p_p -_v. The source code to the preprocessor is distributed in 4Dgifts. This is intended only as a general statement of the preprocessor's capabilities. For a more precise statement, see the C language standard (reference cited at the end of this manual page). The following _o_p_t_i_o_n_s are recognized directly by _a_c_p_p: ----PPPP Preprocess the input without producing the line control information used by the next pass of the C compiler. The compiler driver, _c_c defines appropriate symbols. ----DDDD_n_a_m_e ----DDDD_n_a_m_e=_d_e_f Define _n_a_m_e with value _d_e_f as if by a ####ddddeeeeffffiiiinnnneeee. If no =_d_e_f is given, _n_a_m_e is defined with value 1. The ----DDDD option has lower precedence than the ----UUUU option. That is, if the same name is used in both a ----UUUU options and a ----DDDD option, the name will be undefined regardless of the order of the options. ----IIII_d_i_r Change the algorithm for searching for ####iiiinnnncccclllluuuuddddeeee files whose names do not begin with / to look in _d_i_r before looking in the directories on the standard list. Thus ####iiiinnnncccclllluuuuddddeeee files whose names are enclosed in "" will be searched for first in the directory of the file with the ####iiiinnnncccclllluuuuddddeeee line, then in the directories named in ----IIII options, and last in directories on a standard list. For ####iiiinnnncccclllluuuuddddeeee files whose names are enclosed in <>, the directory of the file with the ####iiiinnnncccclllluuuuddddeeee line is not searched. If ----IIII is given with no _d_i_r, _a_c_p_p is instructed to suppress the search of the standard list of include directories (this form is obsolete, use ----nnnnoooossssttttddddiiiinnnncccc instead)). This standard list consists only of /_u_s_r/_i_n_c_l_u_d_e. ----UUUU_n_a_m_e undefines _n_a_m_e, which is only useful if _n_a_m_e is defined via ----DDDD or is a predefined name. The order of the ----DDDD and ----UUUU options is not significant: the undefines are done after all the ----DDDD's and predefines are applied. PPPPaaaaggggeeee 1111 AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) ----ppppeeeeddddaaaannnnttttiiiicccc All AAAANNNNSSSSIIII constraints are obeyed when this is supplied. Howver, only one ####eeeellllsssseeee, or ####eeeennnnddddiiiiffff with extra tokens after the name is reported per included file to reduce the number of error reports on older header files. ----ttttrrrraaaaddddiiiittttiiiioooonnnnaaaallll Allows dollar($) in identifiers and makes _a_c_p_p behave like a traditional C preprocessor as defined in _T_h_e _C _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l. ----MMMM The names of directly included files are printed on standard output. ----CCCC Comments are retained in the output of _a_c_p_p. ----nnnnoooossssttttddddiiiinnnncccc The standard places are not searched for include files. Use ----IIII to specify directories to search. Ordinarily, only options mentioned on the _c_c(1) man page are of interest. However _a_c_p_p has the following options not recognized by _c_c which can be applied with the _c_c flag prefix ----WWWWpppp,,,,. For example, to apply the _a_c_p_p-only option ----WWWWaaaallllllll, use cccccccc ----WWWWpppp,,,,----WWWWaaaallllllll. ----pppp All AAAANNNNSSSSIIII CCCC constraints are obeyed. If supplied twice, ####iiiiddddeeeennnntttt preprocessing directives produce a warning. Any option starting with -p is considered to mean -pedantic (see above). ----oooo _o_u_t__f_n_a_m_e The output is written to _o_u_t__f_n_a_m_e instead of stdout. ----ttttrrrraaaaddddiiiittttiiiioooonnnnaaaallll Allows dollar($) in identifiers and makes _a_c_p_p behave like a traditional C preprocessor as defined in Kernighan & Ritchie, First Edition. ----ttttrrrriiiiggggrrrraaaapppphhhhssss Turns on processing of trigraphs. ----BBBB Means there is a different, longer, list of default directories to search. And C++ // is understood as a introducing a comment. ----++++ Means there is a different, longer, list of default directories to search. And C++ // is understood as a introducing a comment. ----WWWWttttrrrriiiiggggrrrraaaapppphhhhssss Warns if any trigraphs are encountered in the text. PPPPaaaaggggeeee 2222 AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) ----WWWWccccoooommmmmmmmeeeennnnttttssss Warns if a comment start is found within a comment. ----WWWWccccoooommmmmmmmeeeennnntttt Warns if a comment start is found within a comment. ----WWWWaaaallllllll is the same as having both ----WWWWttttrrrriiiiggggrrrraaaapppphhhhssss and ----WWWWccccoooommmmmmmmeeeennnnttttssss. ----MMMM The names of directly included files are printed on standard output. ----MMMMMMMM The names of included files at all nesting levels are printed on standard output. ----dddd Instead of writing the preprocessed file out, write the names and values of all preprocessor macros defined. ----vvvv prints the GNU CPP version number. ----CCCC Comments are retained in the output of _a_c_p_p. ----$$$$ Dollar signs are allowed in identifiers. ----nnnnoooosssspppplllliiiicccceeee Turn backslash newline into newline when outputting defines, but don't consider them to end the macro definition. ----nnnnoooossssttttddddiiiinnnncccc The standard places are not searched for include files. Use -I to specify directories to search. ----uuuu Inhibits predefinition of values. If not supplied, the names mmmmiiiippppssss and uuuunnnniiiixxxx are predefined. _c_c -_a_n_s_i passes -u to _a_c_p_p. ----wwww Turns off warning messages. ----sssshhhhoooowwwwddddeeeeffffiiiinnnneeeessss Show each #define (#undef) followed by the line number and file name where it is appears. The first few defines shown are the predefines built-in to _c_p_p and passed on the command line (for these the line number and file name are meaningless). This facility is to assist you in the special situation where you have a #define (#undef) and you are having difficulty determining which source file the it is in. Use any standard text tool to inspect the result file. Example: cc -ansi -E -Imyincludedir -Wp,-showdefines myfile.c >myresult ---- As a file name, ---- is treated as a file name (stdin or stdout). PPPPaaaaggggeeee 3333 AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) Some special names are understood by _a_c_p_p. The name ________LLLLIIIINNNNEEEE________ is defined as the current line number (as a decimal integer) as known by _a_c_p_p, and ________FFFFIIIILLLLEEEE________ is defined as the current file name (as a C string) as known by _a_c_p_p. The name ________DDDDAAAATTTTEEEE________ is defined as the date of translation of the source file (a character string literal of the form the names of the months are the same as those generated by the _a_s_c_t_i_m_e(3) function, and the first character of dd is a space character if the value is less than 10). The name ________TTTTIIIIMMMMEEEE________ is defined as the time of translation of the source file (a character string literal of the form generated by the _a_s_c_t_i_m_e(3) function). They can be used anywhere (including in macros) just as any other defined name. To distinguish itself from _c_p_p(1), _a_c_p_p defines the macro ________AAAANNNNSSSSIIII____CCCCPPPPPPPP________, setting its value to one. All _a_c_p_p directive lines start with any number of blanks and tabs followed by ####. Any number of blanks and tabs are allowed between the #### and the directive. The directives are: ####ddddeeeeffffiiiinnnneeee _n_a_m_e _t_o_k_e_n-_s_t_r_i_n_g Replace subsequent instances of _n_a_m_e with _t_o_k_e_n-_s_t_r_i_n_g. ####ddddeeeeffffiiiinnnneeee _n_a_m_e( _a_r_g, ..., _a_r_g ) _t_o_k_e_n-_s_t_r_i_n_g Notice that there can be no space between _n_a_m_e and the (. Replace subsequent instances of _n_a_m_e followed by a (, a list of comma- separated sets of tokens, and a ) followed by _t_o_k_e_n-_s_t_r_i_n_g, where each occurrence of an _a_r_g in the _t_o_k_e_n-_s_t_r_i_n_g is replaced by the corresponding set of tokens in the comma-separated list. When a macro with arguments is expanded, the arguments are placed into the expanded _t_o_k_e_n-_s_t_r_i_n_g unchanged. After the entire _t_o_k_e_n-_s_t_r_i_n_g has been expanded, _a_c_p_p re-starts its scan for names to expand at the beginning of the newly created _t_o_k_e_n-_s_t_r_i_n_g. The #### preprocessing token turns the immediately following argument in _t_o_k_e_n-_s_t_r_i_n_g into a string literal (i.e., enclosed in double quotes) which contains the spelling of the argument (see the example below). The ######## preprocessing token causes the preceeding preprocessing token to be concatenated with the following preprocessing token into a single preprocessing token available for further replacement. Either or both of the preprocessing tokens may be substituted macro arguments. As an example of the #### and ######## operators, the sequence #define quote(arg) # arg #define glue_to_b(a) a ## b quote(foo) glue_to_b(b_follows_me) creates the output "foo" b_follows_meb PPPPaaaaggggeeee 4444 AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) ####uuuunnnnddddeeeeffff _n_a_m_e Cause the definition of _n_a_m_e (if any) to be forgotten from now on. No additional tokens are permitted on the directive line after _n_a_m_e. ####iiiiddddeeeennnntttt "_s_t_r_i_n_g" The _s_t_r_i_n_g and the directive are silently swallowed. No output is produced for this directive. ####pppprrrraaaaggggmmmmaaaa The directive and whatever follows it on the line is passed to the output in a slightly modified form which is not documented. The form may change in a future release. ####pppprrrraaaaggggmmmmaaaa oooonnnncccceeee If this directive appears in an included file, the file will never be included again, even if there is another ####iiiinnnncccclllluuuuddddeeee of this file. No tokens or comments are permitted after the ``once'' keyword. Using ####pppprrrraaaaggggmmmmaaaa oooonnnncccceeee is more efficient than using macro wrappers, because the included file is not rescanned, but it may not be portable to third-party preprocessors. ####iiiinnnncccclllluuuuddddeeee "_f_i_l_e_n_a_m_e" ####iiiinnnncccclllluuuuddddeeee <_f_i_l_e_n_a_m_e> Include at this point the contents of _f_i_l_e_n_a_m_e (which will then be run through _a_c_p_p). When the <_f_i_l_e_n_a_m_e> notation is used, _f_i_l_e_n_a_m_e is only searched for in the standard places. See the ----IIII option above for more detail. No additional tokens are permitted on the directive line after the final " or >. ####lllliiiinnnneeee _i_n_t_e_g_e_r-_c_o_n_s_t_a_n_t _f_i_l_e_n_a_m_e Causes _a_c_p_p to generate line control information for the next pass of the C compiler. _I_n_t_e_g_e_r-_c_o_n_s_t_a_n_t is the line number of the next line and _f_i_l_e_n_a_m_e is the file from which it comes. If "_f_i_l_e_n_a_m_e" is not given, the current file name is unchanged. No additional tokens are premitted on the directive line after the optional _f_i_l_e_n_a_m_e. ####eeeennnnddddiiiiffff Ends a section of lines begun by a test directive (####iiiiffff,,,, ####iiiiffffddddeeeeffff, or ####iiiiffffnnnnddddeeeeffff). Each test directive must have a matching ####eeeennnnddddiiiiffff. No additional tokens are permitted on the directive line. To reduce the volume of error reports on older header files, aaaaccccpppppppp reports only one instance of additional tokens per included file. ####iiiiffffddddeeeeffff _n_a_m_e The lines following will appear in the output if and only if _n_a_m_e has been the subject of a previous ####ddddeeeeffffiiiinnnneeee without being the subject of an intervening ####uuuunnnnddddeeeeffff. No additional tokens are permitted on the directive line after _n_a_m_e. PPPPaaaaggggeeee 5555 AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) ####iiiiffffnnnnddddeeeeffff _n_a_m_e The lines following will appear in the output if and only if _n_a_m_e has not been the subject of a previous ####ddddeeeeffffiiiinnnneeee. No additional tokens are permitted on the directive line after _n_a_m_e. ####iiiiffff _c_o_n_s_t_a_n_t-_e_x_p_r_e_s_s_i_o_n Lines following will appear in the output if and only if the _c_o_n_s_t_a_n_t-_e_x_p_r_e_s_s_i_o_n evaluates to non-zero. All binary non- assignment C operators, the ?: operator, the unary -, !, and ~ operators are all legal in _c_o_n_s_t_a_n_t-_e_x_p_r_e_s_s_i_o_n. The precedence of the operators is the same as defined by the C language. There is also a unary operator ddddeeeeffffiiiinnnneeeedddd, which can be used in _c_o_n_s_t_a_n_t- _e_x_p_r_e_s_s_i_o_n in these two forms: ddddeeeeffffiiiinnnneeeedddd (((( _n_a_m_e )))) or ddddeeeeffffiiiinnnneeeedddd _n_a_m_e. This allows the utility of ####iiiiffffddddeeeeffff and ####iiiiffffnnnnddddeeeeffff in a ####iiiiffff directive. Only these operators, integer constants, and names which are known by _a_c_p_p should be used in _c_o_n_s_t_a_n_t-_e_x_p_r_e_s_s_i_o_n. In particular, the ssssiiiizzzzeeeeooooffff operator is not available. To test whether either of two symbols, _f_o_o and _f_u_m, are defined, use: #if defined(foo) || defined(fum) ####eeeelllliiiiffff _c_o_n_s_t_a_n_t-_e_x_p_r_e_s_s_i_o_n This is equivalent to a #_e_l_s_e with a #_i_f expression, and is often more convenient than a nested #_e_l_s_e #_i_f _c_o_n_s_t_a_n_t-_e_x_p_r_e_s_s_i_o_n #_e_n_d_i_f #_e_n_d_i_f. ####eeeellllsssseeee The lines following will appear in the output if and only if the preceding test directive evaluates to zero. No additional tokens are permitted on the directive line. To reduce the volume of error reports on older header files, aaaaccccpppppppp reports only one instance of additional tokens per included file. The test directives and the possible ####eeeellllsssseeee directives can be nested. ####eeeerrrrrrrroooorrrr _p_r_e_p_r_o_c_e_s_s_i_n_g-_t_o_k_e_n_s The preprocessing tokens are emitted and an error is signaled to _c_c. ####iiiiddddeeeennnntttt This System V directive is silently accepted and ignored unless -_p_e_d_a_n_t_i_c is supplied twice, in which case a warning is issued for each ####iiiiddddeeeennnntttt encountered. ####ssssccccccccssss This is a BSD-only directive. Use of it is an error. FFFFIIIILLLLEEEESSSS standard directory list for ####iiiinnnncccclllluuuuddddeeee files, /usr/include PPPPaaaaggggeeee 6666 AAAACCCCPPPPPPPP((((5555)))) AAAACCCCPPPPPPPP((((5555)))) NNNNOOOOTTTTEEEESSSS Two often-used capabilities of the older C preprocessor _c_p_p(1) have a different syntax in _a_c_p_p(5). These are _e_n_c_l_o_s_i_n_g _a _m_a_c_r_o _a_r_g_u_m_e_n_t _i_n _d_o_u_b_l_e-_q_u_o_t_e_s, and _c_o_n_c_a_t_e_n_a_t_i_n_g _t_o_k_e_n_s. See the discussion of ####ddddeeeeffffiiiinnnneeee for the new syntax. SSSSEEEEEEEE AAAALLLLSSSSOOOO cc(1), line(1), m4(1), cpp(1) American National Standard for Information Systems - Programming Language - C, ANSI X3.159-1989. PPPPaaaaggggeeee 7777